TypeScript WebSocket: Elevating Real-time Communication with Type Safety

            
// types.ts

// Interface for sending a text message
export interface SendMessagePayload {
  roomId: string;
  message: string;
}

// Interface for joining a room
export interface JoinRoomPayload {
  roomId: string;
  userId: string;
}

// Union type for all possible client-to-server messages
export type ClientToServerEvent = 
  | { type: 'SEND_MESSAGE', payload: SendMessagePayload }
  | { type: 'JOIN_ROOM', payload: JoinRoomPayload };

            

              
                Copy
              
            
          

            
// types.ts (continued)

// Interface for a received message in a chat room
export interface ChatMessage {
  id: string;
  roomId: string;
  senderId: string;
  content: string;
  timestamp: number;
}

// Interface for a user joining a room notification
export interface UserJoinedRoomPayload {
  userId: string;
  roomId: string;
  timestamp: number;
}

// Union type for all possible server-to-client messages
export type ServerToClientEvent = 
  | { type: 'NEW_MESSAGE', payload: ChatMessage }
  | { type: 'USER_JOINED', payload: UserJoinedRoomPayload }
  | { type: 'ERROR', payload: { message: string } };

            

              
                Copy
              
            
          

            
// server.ts

import WebSocket, { WebSocketServer } from 'ws';
import { ClientToServerEvent, ServerToClientEvent, ChatMessage, JoinRoomPayload, SendMessagePayload } from './types'; // Assuming types.ts is in the same directory

const wss = new WebSocketServer({ port: 8080 });

console.log('WebSocket server started on port 8080');

wss.on('connection', (ws: WebSocket) => {
  console.log('Client connected');

  ws.on('message', (message: string) => {
    try {
      const parsedMessage: ClientToServerEvent = JSON.parse(message);

      switch (parsedMessage.type) {
        case 'SEND_MESSAGE':
          handleSendMessage(ws, parsedMessage.payload);
          break;
        case 'JOIN_ROOM':
          handleJoinRoom(ws, parsedMessage.payload);
          break;
        default:
          console.warn('Received unknown message type:', parsedMessage);
          sendError(ws, 'Unknown message type');
      }
    } catch (error) {
      console.error('Failed to parse message:', error);
      sendError(ws, 'Invalid JSON received');
    }
  });

  ws.on('close', () => {
    console.log('Client disconnected');
  });

  ws.on('error', (error) => {
    console.error('WebSocket error:', error);
  });

  // Send a welcome message to the client
  sendServerMessage(ws, { type: 'SYSTEM_INFO', payload: { message: 'Welcome to the real-time server!' } });
});

// Helper function to send messages from server to client
function sendServerMessage(ws: WebSocket, message: ServerToClientEvent): void {
  ws.send(JSON.stringify(message));
}

// Helper function to send errors to client
function sendError(ws: WebSocket, errorMessage: string): void {
  sendServerMessage(ws, { type: 'ERROR', payload: { message: errorMessage } });
}

// Specific message handlers
function handleSendMessage(ws: WebSocket, payload: SendMessagePayload): void {
  console.log(`Received message in room ${payload.roomId}: ${payload.message}`);
  // In a real app, you'd broadcast this to other users in the room
  const newMessage: ChatMessage = {
    id: Date.now().toString(), // Simple ID generation
    roomId: payload.roomId,
    senderId: 'anonymous', // In a real app, this would come from authentication
    content: payload.message,
    timestamp: Date.now()
  };
  // Example: Broadcast to all clients (replace with room-specific broadcast)
  wss.clients.forEach(client => {
    if (client !== ws && client.readyState === WebSocket.OPEN) {
      sendServerMessage(client, { type: 'NEW_MESSAGE', payload: newMessage });
    }
  });
  // Optionally send a confirmation back to the sender
  sendServerMessage(ws, { type: 'MESSAGE_SENT', payload: { messageId: newMessage.id } });
}

function handleJoinRoom(ws: WebSocket, payload: JoinRoomPayload): void {
  console.log(`User ${payload.userId} joining room ${payload.roomId}`);
  // In a real app, you'd manage room subscriptions and potentially broadcast to others
  const userJoinedNotification: UserJoinedRoomPayload = {
    userId: payload.userId,
    roomId: payload.roomId,
    timestamp: Date.now()
  };
  // Broadcast to others in the room (example)
  wss.clients.forEach(client => {
    // This requires logic to know which client is in which room
    // For simplicity, we'll just send to everyone here as an example
    if (client.readyState === WebSocket.OPEN) {
      sendServerMessage(client, { type: 'USER_JOINED', payload: userJoinedNotification });
    }
  });
}

// Add a handler for a hypothetical SYSTEM_INFO message type for completeness
// This is an example of how the server might send structured info
// Note: In the above `sendServerMessage` call, we already added a type 'SYSTEM_INFO'
// We'll define it here for clarity, although it's not part of the initial `ServerToClientEvent` union
// In a real app, you'd ensure all defined types are part of the union
interface SystemInfoPayload {
  message: string;
}

// To make the above code compile, we need to add SYSTEM_INFO to ServerToClientEvent
// For this example, let's assume it was added:
// export type ServerToClientEvent = ... | { type: 'SYSTEM_INFO', payload: SystemInfoPayload };

// This demonstrates the need for consistent type definitions.

            

              
                Copy
              
            
          

            
// client.ts

import { ClientToServerEvent, ServerToClientEvent, ChatMessage, UserJoinedRoomPayload } from './types'; // Assuming types.ts is in the same directory

const socket = new WebSocket('ws://localhost:8080');

// Event handlers for the WebSocket connection

socket.onopen = () => {
  console.log('WebSocket connection established');
  // Example: Join a room after connecting
  const joinRoomMessage: ClientToServerEvent = {
    type: 'JOIN_ROOM',
    payload: { roomId: 'general', userId: 'user123' }
  };
  sendMessage(joinRoomMessage);
};

socket.onmessage = (event) => {
  try {
    const message: ServerToClientEvent = JSON.parse(event.data as string);

    switch (message.type) {
      case 'NEW_MESSAGE':
        handleNewMessage(message.payload);
        break;
      case 'USER_JOINED':
        handleUserJoined(message.payload);
        break;
      case 'ERROR':
        console.error('Server error:', message.payload.message);
        break;
      case 'SYSTEM_INFO':
        console.log('System:', message.payload.message);
        break;
      case 'MESSAGE_SENT':
        console.log('Message sent successfully, ID:', message.payload.messageId);
        break;
      default:
        console.warn('Received unknown server message type:', message);
    }
  } catch (error) {
    console.error('Failed to parse server message:', error);
  }
};

socket.onclose = (event) => {
  if (event.wasClean) {
    console.log(`Connection closed cleanly, code=${event.code} reason=${event.reason}`);
  } else {
    console.error('Connection died');
  }
};

socket.onerror = (error) => {
  console.error('WebSocket error:', error);
};

// Function to send messages from client to server
function sendMessage(message: ClientToServerEvent): void {
  if (socket.readyState === WebSocket.OPEN) {
    socket.send(JSON.stringify(message));
  } else {
    console.warn('WebSocket is not open. Cannot send message.');
  }
}

// Example of sending a chat message after connection
function sendChatMessage(room: string, text: string) {
  const message: ClientToServerEvent = {
    type: 'SEND_MESSAGE',
    payload: { roomId: room, message: text }
  };
  sendMessage(message);
}

// Message handlers on the client
function handleNewMessage(message: ChatMessage): void {
  console.log(`
--- New Message in Room ${message.roomId} ---
From: ${message.senderId}
Time: ${new Date(message.timestamp).toLocaleTimeString()}
Content: ${message.content}
---------------------------
`);
  // Update UI with the new message
}

function handleUserJoined(payload: UserJoinedRoomPayload): void {
  console.log(`User ${payload.userId} joined room ${payload.roomId} at ${new Date(payload.timestamp).toLocaleTimeString()}`);
  // Update UI to show new user in room
}

// Example usage:
// setTimeout(() => {
//   sendChatMessage('general', 'Hello, world!');
// }, 3000);

            

              
                Copy
              
            
          

            
// types.ts (extended)

// Generic interface for any server-to-client event
export interface ServerEvent<T = any> {
  type: string;
  payload: T;
}

// Updated ServerToClientEvent using generics implicitly
export type ServerToClientEvent = 
  | ServerEvent<ChatMessage> & { type: 'NEW_MESSAGE' }
  | ServerEvent<UserJoinedRoomPayload> & { type: 'USER_JOINED' }
  | ServerEvent<{ message: string }> & { type: 'ERROR' }
  | ServerEvent<{ message: string }> & { type: 'SYSTEM_INFO' }
  | ServerEvent<{ messageId: string }> & { type: 'MESSAGE_SENT' };

// Example client-side receiver function using generics
function handleServerMessage<T>(event: MessageEvent, expectedType: string, handler: (payload: T) => void): void {
  try {
    const rawMessage = JSON.parse(event.data as string) as ServerEvent;
    if (rawMessage.type === expectedType) {
      handler(rawMessage.payload as T);
    }
  } catch (error) {
    console.error(`Error handling message of type ${expectedType}:`, error);
  }
}

// Usage in client.ts:
// socket.onmessage = (event) => {
//   handleServerMessage<ChatMessage>(event, 'NEW_MESSAGE', handleNewMessage);
//   handleServerMessage<UserJoinedRoomPayload>(event, 'USER_JOINED', handleUserJoined);
//   handleServerMessage<{ message: string }>(event, 'ERROR', (payload) => {
//     console.error('Server error:', payload.message);
//   });
//   // ... and so on
// };

            

              
                Copy
              
            
          

            
// WebSocketService.ts

import { EventEmitter } from 'events';
import { ClientToServerEvent, ServerToClientEvent } from './types';

interface WebSocketServiceOptions {
  url: string;
  reconnectInterval?: number;
  maxReconnectAttempts?: number;
}

export class WebSocketService extends EventEmitter {
  private socket: WebSocket | null = null;
  private url: string;
  private reconnectInterval: number;
  private maxReconnectAttempts: number;
  private reconnectAttempts: number = 0;
  private isConnecting: boolean = false;

  constructor(options: WebSocketServiceOptions) {
    super();
    this.url = options.url;
    this.reconnectInterval = options.reconnectInterval || 5000;
    this.maxReconnectAttempts = options.maxReconnectAttempts || 10;
  }

  connect(): void {
    if (this.socket && this.socket.readyState === WebSocket.OPEN) {
      console.log('Already connected.');
      return;
    }
    if (this.isConnecting) {
        console.log('Connection in progress...');
        return;
    }

    this.isConnecting = true;
    console.log(`Attempting to connect to ${this.url}...`);
    this.socket = new WebSocket(this.url);

    this.socket.onopen = this.onOpen;
    this.socket.onmessage = this.onMessage;
    this.socket.onclose = this.onClose;
    this.socket.onerror = this.onError;
  }

  private onOpen = (): void => {
    console.log('WebSocket connection established.');
    this.reconnectAttempts = 0; // Reset reconnect attempts on successful connection
    this.isConnecting = false;
    this.emit('open');
  };

  private onMessage = (event: MessageEvent): void => {
    try {
      const message = JSON.parse(event.data as string) as ServerToClientEvent;
      this.emit('message', message);
    } catch (error) {
      console.error('Failed to parse message:', error);
      this.emit('error', new Error('Invalid JSON received'));
    }
  };

  private onClose = (event: CloseEvent): void => {
    console.log(`WebSocket connection closed. Code: ${event.code}, Reason: ${event.reason}`);
    this.isConnecting = false;
    this.emit('close', event);
    if (event.code !== 1000) { // 1000 is normal closure
      this.reconnect();
    }
  };

  private onError = (error: Event): void => {
    console.error('WebSocket error:', error);
    this.isConnecting = false;
    this.emit('error', error);
    // Do not auto-reconnect on all errors, depends on the error type if possible
  };

  private reconnect(): void {
    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
      console.error('Max reconnect attempts reached. Giving up.');
      this.emit('maxReconnects');
      return;
    }

    this.reconnectAttempts++;
    console.log(`Attempting to reconnect (${this.reconnectAttempts}/${this.maxReconnectAttempts}) in ${this.reconnectInterval}ms...`);
    setTimeout(() => {
      this.connect();
    }, this.reconnectInterval);
  }

  send(message: ClientToServerEvent): void {
    if (this.socket && this.socket.readyState === WebSocket.OPEN) {
      this.socket.send(JSON.stringify(message));
    } else {
      console.warn('WebSocket is not open. Message not sent.');
      // Optionally queue messages or emit an error
    }
  }

  close(): void {
    if (this.socket) {
      this.socket.close();
    }
  }
}

// Example Usage in your application component/module:
// import { WebSocketService } from './WebSocketService';
// 
// const wsService = new WebSocketService({ url: 'ws://localhost:8080', reconnectInterval: 3000 });
// 
// wsService.on('open', () => {
//   console.log('Connected!');
//   wsService.send({ type: 'SEND_MESSAGE', payload: { roomId: 'general', message: 'Hello from service!' } });
// });
// 
// wsService.on('message', (message: ServerToClientEvent) => {
//   console.log('Received via service:', message);
//   if (message.type === 'NEW_MESSAGE') {
//     // handleNewMessage(message.payload);
//   }
// });
// 
// wsService.on('error', (error) => {
//   console.error('Service encountered an error:', error);
// });
// 
// wsService.on('close', () => {
//   console.log('Service disconnected.');
// });
// 
// wsService.connect();

            

              
                Copy
              
            
          

            
// types.ts (extended)

// Interface for a generic message
interface GenericMessage {
  type: string;
  payload: any;
}

// Type guard to check if a message is of a specific type
function isSendMessagePayload(payload: any): payload is SendMessagePayload {
  return (
    payload &&
    typeof payload.roomId === 'string' &&
    typeof payload.message === 'string'
  );
}

// Using the type guard in server logic
// ... inside wss.on('message') handler ...

// const parsedMessage: any = JSON.parse(message);
// 
// if (parsedMessage && typeof parsedMessage.type === 'string') {
//   switch (parsedMessage.type) {
//     case 'SEND_MESSAGE':
//       if (isSendMessagePayload(parsedMessage.payload)) {
//         handleSendMessage(ws, parsedMessage.payload);
//       } else {
//         sendError(ws, 'Invalid payload for SEND_MESSAGE');
//       }
//       break;
//     // ... other cases
//   }
// } else {
//   sendError(ws, 'Invalid message format');
// }

            

              
                Copy